home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / fortran / f2c-stab.9 / f2c-stab / f2c-stabs / README < prev    next >
Encoding:
Text File  |  1996-03-31  |  7.7 KB  |  196 lines
  1. f2c-stabs - Fortran parsing and symbol table handling for
  2.             f2c/gdb/emacs...
  3. Version 0.9 - ********** Alpha Version ************
  4.  
  5. Copyright (c) 1996 Harvey J. Stein <abel@netvision.net.il>, and
  6. eventually <hjstein@netvision.net.il>
  7. All Rights Reserved.
  8.  
  9. This package is covered by the GNU GPL.  You can freely use and
  10. distribute it as long as it stays under the GNU GPL, and as long as
  11. you distribute all the corresponding source code, and as long as this
  12. message and the above copyright notice remains.
  13.  
  14. Introduction
  15. ------------
  16. This is the f2c-stabs package.  It includes the following:
  17.  
  18.    -A (very weak) Fortran parser called fts-f2si - extracts variable
  19.     declarations, etc from fortran code.
  20.  
  21.    -Emacs elisp code defining a function f2c-gdb - converts a Fortran
  22.     expression into the corresponding C expression that f2c would have
  23.     created, and passes it to GDB for evaluation.  For use when
  24.     running gdb from within emacs on code compiled by f2c.  Figures
  25.     out symbol names, array referencing, etc.
  26.  
  27.    -A script make-f2c-stabs, which takes the output of fts-f2si and
  28.     converts it into the format needed by f2c-gdb.
  29.     
  30.    -A script make-test-routines - Takes the output of fts-f2si and
  31.     generates a "reader" subroutine, a "writer" subroutine, and a
  32.     "driver" program.  Doesn't work so well yet, and requires a
  33.     Fortran i/o library which is such a hack that I'm not currently
  34.     distributing it.
  35.  
  36. This is considered an Alpha testing version because although I and my
  37. coworkers have been using it successfully, this is the first time it's
  38. been released to the Internet, so there are bound to be 
  39.  
  40. Bug Reports, enhancements, and comments
  41. ---------------------------------------
  42.   Bug reports, enhancements and comments to abel@netvision.net.il
  43.   (until hjstein@netvision.net.il exists).
  44.  
  45.   For bug reports, please include enough information to reproduce the
  46.   bug - hardware setup, software versions, source code example, etc.
  47.   Take a look at the emacs info page on reporting bugs for guidelines
  48.   on writing useful bug reports.  Please avoid reporting on bugs that
  49.   are already noted (here or in the scripts), unless it's to say that
  50.   you really desperately need it fixed, in which case it isn't a bug
  51.   report - it's a comment.
  52.  
  53.   For enhancements, please include documentation on how to apply
  54.   and/or use the enhancement.
  55.  
  56. Requirements
  57. ------------
  58.    For f2c-gdb:
  59.       emacs 19
  60.       gdb
  61.  
  62.    For fts-f2si:
  63.       bash (sh will do, probably)
  64.       gawk (I don't know if awk will work)
  65.  
  66.    For make-f2c-stabs and make-test-routines:
  67.       STk (can be gotten by anonymous ftp from kaolin.unice.fr, or
  68.            from sunsite.unc.edu)
  69.       fts-f2si
  70.  
  71. Installation
  72. ------------
  73. 1. Modify scripts if necessary.  For example, you might need to
  74.    change:
  75.     
  76.        #!/bin/bash
  77.        #!/usr/bin/gawk -f
  78.        #!/usr/local/bin/snow
  79.     
  80.    to whatever's appropriate on your system.
  81.  
  82. 2. Modify the Makefile if necessary.  Instructions are included in
  83.    comments at the top of the makefile.
  84.  
  85. 3. Do make.  Make will compile the .el files and move everything to
  86.    the appropriate directories (if you did step 2 correctly).
  87.  
  88. 4. Add (require 'f2c-stabs) and (global-set-key "\C-c\C-v" 'f2c-gdb)
  89.    to your .emacs file.  The former is required, the latter is
  90.    recommended.
  91.  
  92.  
  93. Usage
  94. -----
  95. 1. In your source code directory (which must be the current directory
  96.    when debugging), run:
  97.  
  98.          fts-f2si *.f *.inc
  99.          rm *.el
  100.          make-f2c-stabs *.si
  101.  
  102. This should make a .el file for each .f and .inc that you have in the
  103. current directory.  NOTE - be careful not to accidentally remove any
  104. .el files that you really need.  make-f2c-stabs *appends* symbol table
  105. to the corresponding .el files.  You must remove the old .el files
  106. before making new ones, but you should make sure not to inadvertently
  107. remove something you need.
  108.  
  109. 2. Add the following to your .emacs (if you haven't already):
  110.  
  111.          (require 'f2c-stabs)
  112.          (global-set-key "\C-c\C-v" 'f2c-gdb)
  113.  
  114.  
  115. This will then enable the command C-cC-v when debugging f2c compiled
  116. code from within gud-mode.  This command will prompt (with command
  117. history) for a Fortran expression, and will coerce gdb into printing
  118. its value.  For example, when gdb is stopped in the subroutine
  119. mbs_oas_nt, C-cC-v ref_rate[cp_start, 2*(path+1)] will get expanded
  120. to ((mbsrtnarg_.ref_rate__[((cp_start__+((1+(360-((-
  121. 3)+1)))*(2*(path+1))))-(((- 3)+1)+(1+(360-((- 3)+1)))))])), which will
  122. be passed to gdb for evaluation.
  123.  
  124. Iterators can be used, as long as the arguments are numbers.  For
  125. example, C-cC-v ref_rate[cp_start+6*(0:10), path] would coerce gdb
  126. into printing out every 6th value of ref_rate.
  127.  
  128. Arbitrary Fortran expressions may be used (such as
  129. (ref_rate[2,1]-ref_rate[3,1])/zeroytm[2]).
  130.  
  131. The f2c-gdb command supports completion.  Hitting a <tab> will
  132. complete the symbol before the cursor.  Currently, although local
  133. variables which are scalars can be used in expressions, they are not
  134. loaded into the symbol table data, so completion will not find them.
  135. Note that completion won't work until something's been evaluated in
  136. the current context (to force loading of the symbol tables).
  137.  
  138. Everything is autoloading - f2c-gdb will automatically load the .el
  139. files needed to interpret symbols in the current gdb context.
  140.  
  141. If something doesn't load properly, use the command
  142. f2c-clear-stab-table to clear the symbol tables, and get emacs to
  143. start loading again from scratch.  Also, use f2c-clear-stab-table
  144. after changing source code (and rebuilding corresponding .si and .el
  145. files), and when cahnging the executable that one's debugging.
  146.  
  147. NOTE - Four things that aren't handled:
  148.  
  149.    1. Array dimensions which include parameters - fts-f2si will parse
  150.       them incorrectly.
  151.    2. Parameters which are logicals - f2c-gdb won't translate them
  152.       into the corresponding C values for gdb.  
  153.    3. Exponentiation.  If exponentiation is used in array dimensions
  154.       or in parameter definitions, f2c-gdb won't translate them
  155.       properly.  These you'll have to modify by hand.
  156.    4. Weirdo expressions (such as funky expressions in a & b which,
  157.       because of Fortran's evaluation rules, evaluate to max(a,b)).
  158.  
  159. See comments at the top of f2c-stabs.el for a long detailed
  160. explanation of how to use it.
  161.  
  162. See other scripts and code for other uses, as well as other nifty
  163. functions included in this package.
  164.  
  165. To Do
  166. -----
  167. Anyone who wants to take on any of these tasks, feel free.  But, try
  168. to get in contact with me first, to avoid duplication of effort:
  169.  
  170.    -Better Fortran parsing - fts-f2si.awk is in need of work and/or
  171.     replacement (can't handle parentheses within dimensions
  172.     i.e. -real*8 foo(2*(p1+p2):3*(p1+p2))).
  173.    -Port make-f2c-stabs to elisp.  I should have written it in elisp
  174.     to begin with.  f2c-gdb should autoload the .si files instead of
  175.     the corresponding .el files.  This would alleviate the need for
  176.     STk, something that most people won't have (even though they
  177.     should :).  At least, rename all the .stk code to .scm and make
  178.     it generic enough to also work both with stk and scm.  Please
  179.     someone do this for me :)!
  180.    -Better interface between f2c-gdb and gdb.  Ideally, hitting
  181.     carriage return would parse the current line, doing symbol
  182.     replacements and array dereferencing before giving the line to
  183.     gdb.
  184.    -Clean up interface betwe4en f2c-gdb and gdb - Clearly delineate
  185.     what's gud specific and what's gdb specific, and compartmentalize
  186.     the gdb specific stuff so that people can extend f2c-gdb to work
  187.     with other debuggers.
  188.    -Do same with f2c - Clearly delineate what's f2c specific so that
  189.     this can be used in general to support debugging languages not
  190.     supported by a given debugger.
  191.    -Improve installation procedure to make it more automatic.  Get rid
  192.     of this "edit the scripts and makefile" crap.
  193.  
  194. See other files for additional To Do lists.
  195.  
  196.